feat(propensity): make a reasoned DECLINE learnable — a third state, with a kind - #45

The finding this closes

Three independent audit rounds on 2026-08-23 (Workflows, Trend_Model_Project, Fine-Art-Archive) reached the same conclusion: propensity carried information exactly once, because most candidates sat at the uninformative prior. The missing input was not more consults — it was declines. A capability declined on repo-specific grounds looked byte-identical in the ledger to one nobody ever considered (trig 0, use 0, no 0).

A decline is a THIRD state, not a negative outcome

This is the whole difficulty. A decline means the capability did not run, so recording it as an outcome would bucket it into not_useful — asserting we tried it and it did not help, about something that never executed, corrupting the one signal declines exist to sharpen.

The separation is structural, not conventional: a decline rides on a match event (it genuinely was offered — the only claim the event type makes) tagged source=capability_decline, and usefulness() reads outcome events only. There is no code path from a decline to the posterior. No new event type and no new store: record_promotion already carries a non-match fact on match distinguished by metadata.source.

triggered / declined / not_triggered_silently now partition the candidate set, so "rejected on stated grounds", "offered and ignored" and "never considered" are three different findings. propensity() reports the decline count beside the posterior — "prior, no evidence" and "prior, no evidence, four reasoned rejections" were previously identical readings.

And a decline has a KIND

One undifferentiated count licenses the wrong correction. The third round declined 25 offers across six classes with opposite fixes:

demotable is a property of the kind, declared once in DECLINE_KINDS. An unknown kind is refused rather than coerced — a typo silently becoming unspecified would discard the classification the caller believed it made.

Demotion consumes declines as a second, much lower-floor rule, and the two rules read disjoint populations: never_triggered counts only offers where nothing was said. The first draft counted every offer, so eight honest no_landing_zone declines tripped the silent-non-use rule and demoted a correct match through the back door — the exact wrong correction the taxonomy exists to prevent, arriving via the other rule.

Two attribution defects found on the way

1. The advisor recorded only skill on each match, and the CLI has no --skill flag — so every --surface consult wrote skill: null and the entire control arm of all three audit rounds was unattributable to the surface that produced it. surface is now on the event.
2. detect() enumerated only the declared surface keys. repo-audit:dimension-1 has no table entry — it inherits offload surface-wide — so three audits declining offload there were recorded and never read. A drain that cannot see a surface cannot drain it, and the surfaces most likely to be over-bound are exactly the ones that only inherit.

Reachable from the surfaces that actually decide

CLI decline --capability --experiment --reason --kind --surface, and MCP capability_decline — the callers are skills and bash automations, not Python. The MCP guard is AST-based: a substring check over the handler body was written first and did not discriminate (deleting surface= from the call left the word in the response dict and the break stayed green).

Break→revert, all confirmed to fail without the fix

decline-as-outcome moves the posterior · a blank reason accepted · demotion ignores declines · a triggered capability still demoted · surface attribution dropped · the partition collapses · every kind treated as demotable · the silent rule counting declines · an unknown kind coerced · no_landing_zone demotable · precondition_unmet demotable · surface advertised but not forwarded · reason dropped from the schema · capability_id hardcoded · detect() enumerating declared keys only.

Two of these did not discriminate on the first attempt and were rewritten; both are noted in the code where they live.

Local verdict

python3 verify.py: 365 passed, 82/82 selftests ran, 0 skipped, 4 of 5 gates ok. The 3 pytest failures and the 2 gate failures are pre-existing and machine-local — all five are the evidence-acquisition ledger row (0 references in committed capabilities.py; another session's uncommitted module). Confirmed identical with the change stashed. CI is the verdict.

Contract docs updated (ARCHITECTURE.md, README.md). No diagram change: no stage, component, rail/role classification or role-registry entry moved.